Skip to main content

SourceSync Android SDK

Welcome to the SourceSync Android SDK documentation. This guide will help you understand and implement the SDK's features for synchronizing metadata with content in your Android applications.

Architecture Overview​

The SourceSync Android SDK is architected around several core components that work together to provide synchronized content overlays for video content.

Key Components​

  • SourceSync: Main entry point and controller class
  • Distribution: Content distribution configuration
  • Activation: Individual content pieces for display
  • Overlay System: Manages positioned display containers
  • Segment System: Handles content rendering

Data Flow​

  1. SDK initialization with API key
  2. Distribution loading
  3. Activation processing
  4. Content synchronization
  5. User interaction handling

Core Concepts​

Distributions​

A distribution represents a complete content package curated for SourceSync. It includes:

  • Content metadata
  • Access restrictions
  • Time-aligned activations
  • Analytics configurations

Activations​

Activations are time-synchronized content pieces that appear at specific moments:

  • Preview mode (initial display)
  • Detail mode (expanded view)
  • Custom templates
  • Position information
  • Timing data

Overlay System​

The overlay system manages content display:

  • Multiple simultaneous positions
  • Independent content streams
  • Automatic synchronization
  • Transition effects

Getting Started​

Installation​

  1. Add JitPack repository to your root build.gradle:
allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
  1. Add the dependency to your app's build.gradle:
dependencies {
    implementation 'com.github.Source-Digital.native-sdk:sourcesync-android:v0.0.1'
}

Basic Implementation​

  1. Initialize the SDK:
// Initialize with API key
SourceSync sourcesync = SourceSync.setup(context, "your-api-key");
  1. Load a distribution:
// Load content distribution
Distribution distribution = sourcesync.getDistribution("distribution-id");
  1. Create overlays:
// Create overlay containers
Map<String, View> overlays = sourcesync.createPositionedOverlays(
    distribution, 
    videoView, 
    "top", "bottom", "left", "right"
);

// Add overlays to your layout
layout.addView(overlays.get("top"));
layout.addView(overlays.get("bottom"));

Configuration​

SDK Settings​

Settings can be configured through:

  1. Default configuration
  2. API key settings
  3. Runtime overrides

Example configuration:

{
  "sizeTokens": {
    "xxs": 6,
    "xs": 10,
    "sm": 14,
    "md": 16,
    "lg": 20,
    "xl": 24,
    "xxl": 32
  },
  "overlay": {
    "defaultPadding": 16,
    "defaultOpacity": 0.8
  }
}

Custom Settings​

You can provide custom settings during initialization:

JSONObject customSettings = new JSONObject()
    .put("overlay", new JSONObject()
        .put("defaultPadding", 20)
        .put("defaultOpacity", 0.9));

SourceSync sourcesync = SourceSync.setup(context, "your-api-key", customSettings);

Advanced Features​

Custom Templates​

Create custom templates using the native render system:

{
  "type": "NativeBlock",
  "settings": {
    "segments": [
      {
        "type": "text",
        "content": "Custom content",
        "attributes": {
          "size": "lg",
          "color": "#FFFFFF"
        }
      }
    ]
  }
}

Programmatic Activations​

Create activations dynamically:

JSONObject activationJson = new JSONObject()
    .put("id", 1)
    .put("name", "Dynamic Activation")
    .put("instances", new JSONArray()
        .put(new JSONObject()
            .put("when", new JSONObject()
                .put("start", 1000)
                .put("end", 5000))));

Activation activation = Activation.fromJson(activationJson);

Position Mapping​

Map activation targets to specific overlay positions:

Map<String, View> overlays = sourcesync.createPositionedOverlays(
    distribution,
    videoView,
    "top", "bottom", "left", "right"
);

Best Practices​

Performance Optimization​

  1. Preload Activations

    • Load distributions early
    • Cache frequently used content
    • Initialize overlays before playback

  2. Resource Management

    • Optimize image resources
    • Use appropriate template complexity
    • Monitor memory usage

User Experience​

  1. Content Placement

    • Maintain consistent positioning
    • Use appropriate timing
    • Implement smooth transitions

  2. Interaction Design

    • Provide clear interaction cues
    • Handle orientation changes
    • Manage focus appropriately

Error Handling​

  1. Input Validation

    • Validate all JSON inputs
    • Check configuration values
    • Verify activation timing

  2. Network Handling

    • Handle network failures gracefully
    • Provide fallback content
    • Implement retry logic

  3. Logging

    • Log errors appropriately
    • Include relevant context
    • Track performance metrics

Troubleshooting​

Common Issues​

  1. Overlay Not Displaying

    • Verify API key
    • Check distribution ID
    • Validate JSON format
    • Inspect layout parameters

  2. Timing Issues

    • Check video position
    • Verify activation windows
    • Monitor playback state

  3. Template Problems

    • Validate segment types
    • Check attributes
    • Verify size tokens

Debug Mode​

Enable debug logging:

// Enable debug logging (implementation pending)
SourceSync.setDebugMode(true);

API Reference​

SourceSync Class​

Main SDK controller class.

public class SourceSync {
    // Initialize SDK
    public static SourceSync setup(Context context, String apiKey)
    
    // Get distribution
    public Distribution getDistribution(String id)
    
    // Create overlays
    public Map<String, View> createPositionedOverlays(
        Distribution distribution,
        VideoView videoView,
        String... positions)
}

Distribution Class​

Manages content distribution configuration.

public class Distribution {
    public final int id;
    public final String name;
    public final List<ActivationInstance> activations;
}

Activation Class​

Handles individual content pieces.

public class Activation {
    public final int id;
    public final String name;
    public final JSONObject settings;
    public final JSONArray template;
}

License​

Copyright © 2025 Source Digital, Inc.

Licensed under the Apache License, Version 2.0. For full license text, see LICENSE file in the repository.